Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generate docs from Markdown with Pandoc #3186

Open
wants to merge 3 commits into
base: master
Choose a base branch
from

Conversation

01mf02
Copy link

@01mf02 01mf02 commented Sep 30, 2024

This PR changes the format of the user manual from YAML to Markdown.
This gives a multitude of benefits, including better editor support, smaller files, better tooling, and more flexible document structure.
The idea is that manuals for old jq versions (1.3 to 1.7) remain untouched as YAML, whereas new documentation is written in Markdown (docs/content/manual/manual.md). When new features are added to jq, they can be documented in the manual with a compatibility note, which should allow to document all future jq versions in one file.

I've tried to preserve the look as much as possible, but there are still a few aesthetic differences compared to the current manual, especially concerning the styling of examples. If these are important to you, I can try to make them more similar.

A preview of the current state:

Screenshot 2024-09-30 at 17-26-31 jq Manual

What works:

  • Manpage generation
  • Test generation from manual (man.test, manonig.test)
  • Table of contents generation
  • Search index generation
  • Links to jq-play.org for running examples

What does not work:

  • Automatic detection of Pandoc to build documentation: I am not autotools wizard, so I changed documentation building by default to false. That means you need to run ./configure --enable-docs even if you have all required dependencies (i.e. Pandoc).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant